Aminet 5

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / libs / SSLib51.lha / SSLib.doc < prev next >

Wrap

Text File | 1995-01-16 | 82KB | 3,050 lines

TABLE OF CONTENTS ss.library/AddExtension ss.library/AddHashItem ss.library/BFlush ss.library/BGetByte ss.library/BGetLong ss.library/BGets ss.library/BGetString ss.library/BGetWord ss.library/BPrintf ss.library/BPutByte ss.library/BPutChar ss.library/BPutLong ss.library/BPuts ss.library/BPutsNL ss.library/BPutString ss.library/BPutWord ss.library/BRead ss.library/BRelSeek ss.library/BSeek ss.library/BTell ss.library/BUnGetc ss.library/BWrite ss.library/CallBlock ss.library/ChkDoIO ss.library/ChkRead ss.library/ChkTryRead ss.library/ChkWrite ss.library/CreateResList ss.library/DisplayError ss.library/DosError ss.library/ExitCleanup ss.library/ExitError ss.library/FindHashItem ss.library/FormatStr ss.library/FreeAllResLists ss.library/FreeObject ss.library/FreeResList ss.library/GetExtension ss.library/GetResList ss.library/InitHashTree ss.library/IPAlloc ss.library/IPFree ss.library/LinearAlloc ss.library/LinearAllocN ss.library/LoadFile ss.library/MergeResLists ss.library/ParseArgs ss.library/PoolAlloc ss.library/PoolFree ss.library/Printf ss.library/Puts ss.library/PutsNL ss.library/QuickSort ss.library/RelinkObject ss.library/RemExtension ss.library/ReportError ss.library/SetExtension ss.library/SimpleRequest ss.library/SortList ss.library/SortListName ss.library/SortLongs ss.library/SortStrings ss.library/StartupInit ss.library/StrCat ss.library/StrToL ss.library/TestBreak ss.library/TestStack ss.library/TrackAlloc ss.library/TrackAllocMem ss.library/TrackAllocPub ss.library/TrackBufHandle ss.library/TrackDevice ss.library/TrackDosObject ss.library/TrackExtd ss.library/TrackIoRq ss.library/TrackLibrary ss.library/TrackLinPool ss.library/TrackLock ss.library/TrackObject ss.library/TrackOpen ss.library/TrackOpenBuf ss.library/TrackOpenBufFH ss.library/TrackPool ss.library/TrackPort ss.library/TrackRoutine ss.library/TrackSignal ss.library/TrackSlave ss.library/AddExtension ss.library/AddExtension NAME AddExtension -- Add extension to file name. SYNOPSIS Success = AddExtension(Name, Buffer, Extension, BufSize); D0 A0 A1 A2 D0 FUNCTION Appends an extension to file name. If there's already some extension at the end of the name, nothing happens. INPUTS Name - original file name Buffer - buffer to copy the result to Extension - extension to be added BufSize - size of the buffer RESULT Success - TRUE if successful, FALSE if buffer overflow. SEE ALSO SetExtension, GetExtension, RemExtension ss.library/AddHashItem ss.library/AddHashItem NAME AddHashItem -- Add item to hashed tree. SYNOPSIS UserData = AddHashItem(Tree, ItemName, DataSize); D0 A0 A1 D0 FUNCTION Add an item to hashed tree performing no checking of duplicity (if you make duplicated entries, some of them will be lost and cannot be found by any method, but are correctly freed if you free the tree). The item contains your own data area of specified size, which is guaranteed to be filled by zeroes. INPUTS Tree - hashed tree represented by its tracker ItemName - text key representing the item DataSize - the size of your data area for the item (0-32766, must be even!) RESULT UserData - Pointer to user data area of the item. This data area is preceeded by one word containing size of the area. The area is succeeded by key string. SEE ALSO InitHashTree, FindHashItem, FreeObject ss.library/BFlush ss.library/BFlush NAME BFlush -- Flush a buffered stream SYNOPSIS BFlush(Stream); A2 FUNCTION Flush all information stored in stream buffers. If it's a read stream, buffered bytes are simply forgotten and the file is seeked to reflect new position if needed. If it's a write stream, the buffer is simply written to the file. INPUTS Stream - I/O stream tracker SEE ALSO TrackOpenBuf, TrackOpenBufFH, TrackBufHandle ss.library/BGetByte ss.library/BGetByte NAME BGetByte -- Get one byte from buffered I/O stream SYNOPSIS Byte = BGetByte(Stream); D0 A2 FUNCTION Get one byte from buffered I/O stream opened for reading. If there are no more bytes available, returns -1 as an EOF mark. (it's possible to check this as a negative result, because it's the only negative result given) The biob_eof bit is set if EOF has been encountered. INPUTS Stream - I/O stream handle RESULT Byte - byte got (extended to unsigned longword) or -1 if EOF. NOTE This call modifies only A0 and D0. A6 is not required to contain SSLib base. This function can be easily inlined as: move.l bh_current(A2),A0 cmp.l bh_dataend(A2),A0 beq.s .over moveq #0,D0 move.b (A0)+,D0 move.l A0,bh_current(A2) bra.s .okay .over call ss,BGetByte .okay SEE ALSO TrackOpenBuf, TrackBufHandle, BGetWord, BGetLong, BPutByte, BPutChar ss.library/BGetLong ss.library/BGetLong NAME BGetLong -- Get one longword from buffered I/O stream SYNOPSIS Long, EOF = BGetLong(Stream); D0 D1 A2 FUNCTION Get one longword from buffered I/O stream opened for reading. If there are no more longwords available, returns EOF=-1 (it's possible to check this as a negative result, because it's the only negative result given) If it isn't possible to fetch the whole longword, EOF is returned and the remaining 1-3 bytes are left in the buffer. The biob_eof bit is set if EOF has been encountered, but not if several bytes remain and EOF has been signalled via result. INPUTS Stream - I/O stream handle RESULT Long - longword got (or -1 if EOF) EOF (D1) - set to -1 if EOF (less than 4 bytes available). In other cases zero. NOTE This call modifies only A0 and D0/D1. A6 is not required to contain SSLib base. SEE ALSO TrackOpenBuf, TrackBufHandle, BGetByte, BGetWord, BPutLong ss.library/BGets ss.library/BGets NAME BGets -- Get an EOL-terminated string SYNOPSIS Success = BGets(Buffer, Size, Stream); D0 A0 D0 A2 FUNCTION Read an EOL-terminated string into user-supplied buffer of specified size. When the string doesn't fit in the buffer, the buffer overflow error (err_over) is reported and program execution is stopped if the corresponding error bit is active. Even in this case, the partial string stored in the buffer is guaranteed to be null-terminated. When EOF is encountered in the middle of some string, the already read part of the string is terminated by zero and EOF is returned. INPUTS Buffer - buffer to read the string to Size - buffer size (1<Size<65536) Stream - I/O stream handle RESULT Success - 0 if buffer overflow, 1 if string read OK, -1 if EOF NOTE The EOL character itself is NOT stored into the buffer. NUL character is also recognised as an EOL. SEE ALSO BGetString, BPuts, BPutsNL ss.library/BGetString ss.library/BGetString NAME BGetString -- Get a null-terminated string SYNOPSIS Success = BGetString(Buffer, Size, Stream); D0 A0 D0 A2 FUNCTION Read a null-terminated string into user-supplied buffer of specified size. When the string doesn't fit in the buffer, the buffer overflow error (err_over) is reported and program execution is stopped if the corresponding error bit is active. Even in this case, the partial string stored in the buffer is guaranteed to be null-terminated. When EOF is encountered in the middle of some string, the already read part of the string is terminated by zero and EOF is returned. INPUTS Buffer - buffer to read the string to Size - buffer size (1<Size<65536) Stream - I/O stream handle RESULT Success - 0 if buffer overflow, 1 if string read OK, -1 if EOF SEE ALSO BGets, BPutString ss.library/BGetWord ss.library/BGetWord NAME BGetWord -- Get one word from buffered I/O stream SYNOPSIS Word = BGetWord(Stream); D0 A2 FUNCTION Get one word from buffered I/O stream opened for reading. If there are no more words available, returns -1 as an EOF mark. (it's possible to check this as a negative result, because it's the only negative result given) If it isn't possible to fetch the whole word, EOF is returned and the remaining byte is left in the buffer. The biob_eof bit is set if EOF has been encountered, but not if one byte remains and EOF has been signalled via result. INPUTS Stream - I/O stream handle RESULT Word - word got (extended to unsigned longword) or -1 if EOF. NOTE This call modifies only A0 and D0. A6 is not required to contain SSLib base. SEE ALSO TrackOpenBuf, TrackBufHandle, BGetByte, BGetLong, BPutWord ss.library/BPrintf ss.library/BPrintf NAME BPrintf -- Printf to buffered I/O stream SYNOPSIS BPrintf(Text, Params, Stream); A0 A1 A3 FUNCTION Calls a RawDoFmt with PutChProc = BPutChar doing formatted output to buffered I/O stream. INPUTS Text - pointer to format string Params - pointer to parameter array Stream - I/O stream handle SEE ALSO BPuts, BPutsNL, Printf, exec.library/RawDoFmt ss.library/BPutByte ss.library/BPutByte NAME BPutByte -- Put one byte to buffered stream SYNOPSIS BPutByte(Byte, Stream); D0.B A3 FUNCTION Put one byte to buffered I/O stream opened for writing. This function should be used for writing of streams which don't have the line buffering mode set, because it contains no checks for line end characters. INPUTS Byte - byte to be written Stream - I/O stream handle NOTE This call modifies only A0. A6 is not required to contain SSLib base. A5 can also contain illegal values, which makes this function suitable for calling from non-SS environments. Can be inlined easily as: move.l bh_current(A3),A0 cmp.l bh_bufend(A3),A0 beq.s .over move.b D0,(A0)+ move.l A0,bh_current(A3) bra.s .okay .over call ss,BPutByte .okay SEE ALSO TrackOpenBuf, TrackBufHandle, BPutWord, BPutLong, BGetByte, BPutChar ss.library/BPutChar ss.library/BPutChar NAME BPutChar -- Put one character to buffered stream SYNOPSIS BPutChar(Char, Stream); D0.B A3 FUNCTION Put one character to buffered I/O stream opened for writing. This function performs EOL-checking and can be used on streams with line buffering mode set. If don't use this mode, you should better use BPutChar which contains no additional checks and is slightly faster. INPUTS Char - character to be written Stream - I/O stream handle NOTE This call modifies only A0. A6 is not required to contain SSLib base. A5 can also contain illegal values, which makes this function suitable for calling from non-SS environments. SEE ALSO TrackOpenBuf, TrackBufHandle, BPutByte, BGetByte ss.library/BPutLong ss.library/BPutLong NAME BPutLong -- Put one longword to buffered stream SYNOPSIS BPutLong(Long, Stream); D0 A3 FUNCTION Put one longword to buffered I/O stream opened for writing. This function should be used for writing of streams which don't have the line buffering mode set, because it contains no checks for line end characters. INPUTS Long - longword to be written Stream - I/O stream handle NOTE This call modifies only A0 and D0. A6 is not required to contain SSLib base. SEE ALSO TrackOpenBuf, TrackBufHandle, BPutWord, BPutLong, BGetLong ss.library/BPuts ss.library/BPuts NAME BPuts -- Put string SYNOPSIS BPuts(String, Stream); A0 A3 FUNCTION This function writes a string to buffered I/O stream opened for writing. The string is not terminated by any special byte. This function performs EOL-checking and can be used on streams with line buffering mode set. INPUTS String - string to be put Stream - I/O stream handle SEE ALSO TrackOpenBuf,TrackBufHandle, BPutChar, BPutString, BPutsNL ss.library/BPutsNL ss.library/BPutsNL NAME BPutsNL -- Put EOL-terminated string SYNOPSIS BPutsNL(String, Stream); A0 A3 FUNCTION This function writes a string to buffered I/O stream opened for writing. The string is terminated by an EOL character. This function performs EOL-checking and can be used on streams with line buffering mode set. INPUTS String - string to be put Stream - I/O stream handle SEE ALSO TrackOpenBuf,TrackBufHandle, BPutChar, BPutString, BPuts ss.library/BPutString ss.library/BPutString NAME BPutString -- Put null-terminated string SYNOPSIS BPutString(String, Stream); A0 A3 FUNCTION This function writes a string to buffered I/O stream opened for writing. The string is succeeded by terminating zero byte. This function should be used for writing of streams which don't have the line buffering mode set, because it contains no checks for line end characters. INPUTS String - string to be put Stream - I/O stream handle SEE ALSO TrackOpenBuf,TrackBufHandle, BPutByte, BPuts, BPutsNL ss.library/BPutWord ss.library/BPutWord NAME BPutWord -- Put one word to buffered stream SYNOPSIS BPutWord(Word, Stream); D0.W A3 FUNCTION Put one word to buffered I/O stream opened for writing. This function should be used for writing of streams which don't have the line buffering mode set, because it contains no checks for line end characters. INPUTS Word - word to be written Stream - I/O stream handle NOTE This call modifies only A0. A6 is not required to contain SSLib base. SEE ALSO TrackOpenBuf, TrackBufHandle, BPutByte, BPutLong, BGetWord ss.library/BRead ss.library/BRead NAME BRead -- Read block from buffered I/O stream SYNOPSIS Size = BRead(Buffer, Size, Stream); D0 A0 D0 A2 FUNCTION Reads a block of given size from buffered I/O stream. If less then Size bytes are available, only partial read is done and the real number of bytes read is returned. INPUTS Buffer - buffer to read the block to Size - block size Stream - stream to read from RESULT Size - number of bytes read (0=EOF) SEE ALSO TrackOpenBuf, TrackBufHandle, BGetByte, BWrite ss.library/BRelSeek ss.library/BRelSeek NAME BRelSeek -- Relative seek in buffered I/O stream SYNOPSIS BRelSeek(Stream, Position); A2 D0 FUNCTION Advance position in buffered I/O stream opened for reading by given amount. bh_seekfunc must be available to do this. INPUTS Stream - stream to seek in Position - position to move by NOTE The biob_eof flag bit is reset. SEE ALSO BSeek, BTell, TrackOpenBuf, TrackBufHandle ss.library/BSeek ss.library/BSeek NAME BSeek -- Seek in buffered I/O stream SYNOPSIS BSeek(Stream, Position); A2 D0 FUNCTION Sets position in buffered I/O stream opened for reading to given value . bh_seekfunc must be available to do this. INPUTS Stream - stream to seek in Position - position to move to NOTE The biob_eof flag bit is reset. SEE ALSO BRelSeek, BTell, TrackOpenBuf, TrackBufHandle ss.library/BTell ss.library/BTell NAME BTell -- Get current position in buffered I/O stream SYNOPSIS Position = BTell(Stream); D0 A2 FUNCTION Calculates current position in given buffered I/O stream. Both read and write streams may be used. INPUTS Stream - stream to get position of RESULT Position - current position in given stream NOTE This function modifies only D0. Can be inlined easily as: move.l bh_current(A2),D0 sub.l bh_buffer(A2),D0 add.l bh_position(A2),D0 SEE ALSO BSeek, BRelSeek, TrackOpenBuf, TrackBufHandle ss.library/BUnGetc ss.library/BUnGetc NAME BUnGetc -- Push back one character to I/O stream SYNOPSIS BUnGetc(Char, Stream); D0 A2 FUNCTION For read streams: Pushes given character back to the stream buffer. It's possible to push back only one character without reading it. If applied to write streams, it discards the last character written. Only the recently written character may be discarded. The Char parameter is ignored. It is not possible to undo last character written by BWrite. If you seek the read stream you have pushed the character back, you can obtain this character in its original or changed form, depending on local conditions. To avoid this strange behavior, use BFlush before seeking. INPUTS Char - character to be pushed back Stream - stream to push the character to NOTE This call modifies only A0. A6 is not required to contain SSLib base. Can be inlined easily as: move.l bh_current(A2),A0 move.b D0,-(A0) move.l A0,bh_current(A2) SEE ALSO BGetByte, BPutByte, BGetChar ss.library/BWrite ss.library/BWrite NAME BWrite -- Write block to buffered I/O stream SYNOPSIS BWrite(Buffer, Size, Stream); A0 D0 A3 FUNCTION Writes a block of given size to buffered I/O stream. This function should be used for writing of streams which don't have the line buffering mode set, because it contains no checks for line end characters. INPUTS Buffer - block to be written Size - block size Stream - stream to write to SEE ALSO TrackOpenBuf, TrackBufHandle, BPutByte, BRead ss.library/CallBlock ss.library/CallBlock NAME CallBlock -- Call a subprogram. SYNOPSIS Failure = CallBlock(Routine, LeaveResources); D0 A0 D0 FUNCTION Calls a subprogram. If the subprogram fails or LeaveResources=0, all resources allocated by it are freed. If it doesn't fail and LeaveResources<>0, these resources are added to current resource list of the caller. Registers D1-D7/A0-A6 are passed to called subprogram without changes. If it returns normally, D1-D7/A0-A4/A6 are passed back to the caller. In case of failure (return via ExitError), D2-D7/A2-A6 contain their original values (before call), values of D1/A0-A1 are unexpectable. INPUTS Routine - address of subroutine to be called LeaveResources - boolean value indicating that you want the resources allocated by the subprogram to be allocated. If not set, they are freed automatically before return. RESULT Failure - non-zero value if the routine has failed. NOTE The called subprogram is not allowed to create its own resource lists. SEE ALSO MergeResLists ss.library/ChkDoIO ss.library/ChkDoIO NAME ChkDoIO -- Perform an I/O operation and test error. SYNOPSIS Error = ChkDoIO(Message, DeviceTracker); D0 A0 A1 FUNCTION This function acts like DoIO in exec.library with the following differences, which make it easier to use in programs doing simple I/O: - IO_FLAGS are NOT set to $01 (DoIO does it, but ChkDoIO sets only the IOB_QUICK bit). It makes ChkDoIO capable of handling I/O commands requiring special information in flags. - While waiting for finish of the operation, the user may hit CTRL-C and try to abort it. - If err_iofail and err_iofail2 bits are set, ChkDoIO does automatic processing of I/O errors. In this case, it uses the error table stored in the device tracker (see TrackDevice) and the custom error string. If the error string has been found, "<Message> - <error string>" is displayed and err_iofail2 is used. In other cases, "<Message> - <xxx.device> error <errcode>" and err_iofail is used. INPUTS Message - optional error message (if NULL, "I/O error" will be used) DeviceTracker - tracker of device to perform the I/O operation with. It must contain reference to the error table (may be NULL). RESULT Error - error code or 0 if successful. WARNING It is not possible to use ChkDoIO on device trackers which don't contain the error table. A NULL pointer is a valid error table. SEE ALSO TrackDevice, exec/DoIO ss.library/ChkRead ss.library/ChkRead NAME ChkRead -- Read from file and test error or EOF. SYNOPSIS Success = ChkRead(Tracker, Buffer, Size); D0 A0 A1 D0 FUNCTION Read from file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reporting. The report is generated whenever the size of read data is not equal to the size specified as a parameter, therefore ChkRead cannot be used for reading from interactive files (consoles etc.). INPUTS Tracker - tracker of file to read the data from. Buffer - buffer to read the data to. Size - size of block you want to read. RESULT Success - boolean value indicating success. WARNING File name specified by a call to TrackFile must be still on its place and mustn't be changed in any way. SEE ALSO ChkTryRead, ChkWrite, TrackOpen, LoadFile ss.library/ChkTryRead ss.library/ChkTryRead NAME ChkTryRead -- Read from file and test error. SYNOPSIS Size = ChkTryRead(Tracker, Buffer, Size); D0 A0 A1 D0 FUNCTION Read from file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reporting. INPUTS Tracker - tracker of file to read the data from. Buffer - buffer to read the data to. Size - maximal size of block you want to read. RESULT Size - number of bytes read. 0 if EOF. WARNING File name specified by a call to TrackFile must be still on its place and mustn't be changed in any way. NOTE If the err_read bit is not set, you cannot see whether the zero value returned is caused by read error or EOF. But if you don't have the error bit set, ChkTryRead is functionally equivalent to dos/Read. SEE ALSO ChkRead, ChkWrite, TrackOpen, LoadFile ss.library/ChkWrite ss.library/ChkWrite NAME ChkWrite -- Write to file and test error. SYNOPSIS Success = ChkWrite(Tracker, Buffer, Size); D0 A0 A1 D0 FUNCTION Write to file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reporting. The report is generated whenever the size of written data is not equal to the size specified as a parameter. INPUTS Tracker - tracker of file to write the data to. Buffer - address of data to be written. Size - size of block you want to write. RESULT Success - boolean value indicating success. WARNING File name specified by a call to TrackFile must be still on its place and mustn't be changed in any way. SEE ALSO ChkRead, TrackOpen ss.library/CreateResList ss.library/CreateResList NAME CreateResList -- Create new resource list. SYNOPSIS ResList = CreateResList(); D0 FUNCTION Create local resource list. It can be useful if you need to have local resources allocated in some part of program and freed after leaving it and you don't want to free them separately by FreeObject(). RESULT ResList - Pointer to created ResourceList structure. SEE ALSO FreeResList, FreeAllResLists ss.library/DisplayError ss.library/DisplayError NAME DisplayError -- Display error message without exiting. SYNOPSIS DisplayError(Text, Params); A0 A1 FUNCTION Display an error message using standard or user-supplied error displaying mechanism (it defaults to writing of the message into standard output if it exists or to displaying a requester with it if started from WB with no console window). Using of requesters (equivalent to SimpleRequest(A0,A1,"Exit")) for the default error routine can be forced by the ssf_errorreq flag or the sst_errorreq tag. This function automatically adds an exclamation mark ('!') to the message and is able to process printf-style arguments. It's better if the error message isn't longer than one line. INPUTS Text - pointer to message you want to display (MUSTN'T EXCEED 200 BYTES!!!) Params - pointer to optional parameters used for printf-style formatting SEE ALSO ExitError, DosError, ReportError, SimpleRequest, exec/RawDoFmt ss.library/DosError ss.library/DosError NAME DosError -- Exit with DOS error. SYNOPSIS DosError(Text, Params); A0 A1 FUNCTION Display an error message followed by DOS fault string explaining why did error happen. The DOS error number is determined from the dos/IoErr() function, therefore you must call DosError() directly after the function, which caused the error without calling any other DOS functions (directly or indirectly). The program is terminated via standard exit mechanism with return code according to sv_errrc. If IoErr() returns zero (no error cause known), the supplied message is simply passed to ExitError(). If there is no such message, "Unknown DOS Error" is used. INPUTS Text - message text, can be empty (in this case, only the fault string is shown). Params - pointer to optional parameters used for printf-style formatting. NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO ExitCleanup, ExitError ss.library/ExitCleanup ss.library/ExitCleanup NAME ExitCleanup -- Clean up and exit. SYNOPSIS ExitCleanup(); FUNCTION This service exits the program after performing some cleanup actions: - A5 is tested for correct value. If it contains garbage, the current task is searched for in the caller table. If it isn't found, the alert AN_ExitCrash is displayed. (this very fatal situation shouldn't occur). - the user's exit routine (sv_exitrout) is called. - all tracked resources are freed using FreeAllResLists(). - all arguments supplied by DOS are freed. - the block of variables pointed to by A5 is freed. - some other actions which needn't to be described here. RESULT Completely clean environment (all objects can be recycled...) NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO StartupInit, ExitError, DosError ss.library/ExitError ss.library/ExitError NAME ExitError -- Display error message and exit. SYNOPSIS ExitError(Text, Params); A0 A1 FUNCTION Display an error message using DisplayError and exit the program with return code sv_errrc. It's better if the error message isn't longer than one line. INPUTS Text - pointer to error message (MUSTN'T EXCEED 200 BYTES!!!) Params - optional pointer for parameters used for printf-style formatting RESULT Horrified user. NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO DisplayError, ExitCleanup ss.library/FindHashItem ss.library/FindHashItem NAME FindHashItem -- Find item in hashed tree. SYNOPSIS UserDate = FindHashItem(Tree, ItemName); D0 A0 A1 FUNCTION Find an item in hashed tree. It's able to find only one occurence of given string. INPUTS Tree - hashed tree represented by its tracker ItemName - text key to find RESULT UserDate - Pointer to user data area of the item. (Additional fields reachable from this point are listed in AddHashItem doc). NULL if not found. SEE ALSO InitHashTree, AddHashItem, FreeObject ss.library/FormatStr ss.library/FormatStr NAME FormatStr -- Format data according to template. SYNOPSIS FormatStr(Format, Data, DestBuf); A0 A1 A2 FUNCTION This function performs something like sprintf() in C. It calls exec/RawDoFmt with simple PutC routine, which stores all characters into supplied destination buffer. INPUTS Format - pointer to format string Data - pointer to parameters DestBuf - pointer to destination buffer ss.library/FreeAllResLists ss.library/FreeAllResLists NAME FreeAllResLists -- Free all resource lists. SYNOPSIS FreeAllResLists(); FUNCTION Free all tracked resources in all resource lists and discard all the lists. Used by ExitCleanup(). SEE ALSO FreeResList, ExitCleanup ss.library/FreeObject ss.library/FreeObject NAME FreeObject -- Free tracked object. SYNOPSIS FreeObject(Tracker); A0 FUNCTION Free tracked object and remove the tracker. For master trackers, free all slave trackers. All trackers, which are not freed by calling of this service, will be freed during the ExitCleanup process. It will be done in reverse order of their tracking. Trackers connected as slaves will be handled as usually (see below). The freeing routines may fail. In this case, the resource freeing process will be started again and the tracker will be freed without calling the routine which caused the failure. The freeing routine for given tracker type is called only if the trk_data field is not 0. But the tracker itself is freed in any case. If you free a tracker, which is a slave of some other tracker, the tracked resource is correctly freed, but the tracker node remains in memory until the master tracker is freed. INPUTS Tracker - pointer to tracked object to be freed. SEE ALSO FreeResList, Track#?, FreeAllResLists, ExitCleanup ss.library/FreeResList ss.library/FreeResList NAME FreeResList -- Free resource list. SYNOPSIS FreeResList(); FUNCTION Free all tracked objects in the top-level resource list and remove the list. Used to free local resource lists. The object are removed in head-to-tail order, therefore the object list acts as a LIFO buffer. SEE ALSO CreateResList, FreeAllResLists, FreeObject, Track#?, ExitCleanup ss.library/GetExtension ss.library/GetExtension NAME GetExtension -- Get filename extension. SYNOPSIS Extension = GetExtension(Name); D0 A0 FUNCTION Get last extension of given filename. INPUTS Name - file name you want to get extension of RESULT Extension - Pointer to extension of the file name. If there's no extension, the pointer points to the trailing NULL character of the name. NOTE A0=D0 on exit. SEE ALSO AddExtension, GetExtension, RemExtension ss.library/GetResList ss.library/GetResList NAME GetResList -- Get pointer to current resource list. SYNOPSIS RList = GetResList(); D0 FUNCTION Get current top-level resource list. If there is no resource list, new one is created. RESULT RList - pointer to the resl_list item of the top-level resource list. NOTE A0=D0 on exit. SEE ALSO CreateResList, FreeResList, Track#? ss.library/InitHashTree ss.library/InitHashTree NAME InitHashTree -- Initialize a hashed tree. SYNOPSIS Tracker = InitHashTree(TableSize, Flags); D0 D0 D1 FUNCTION Initialize a hashed tree. The hashed tree is a simple structure containing data items accessed using text key. SS Library allows to simply manage these trees with both case-dependent and case-independent key searching. INPUTS TableSize - number of entries in the hash table. Each entry occupies 4 bytes. Must be a power of 2 between 8 and 32768. Flags - htf_nocase if all the comparisons have to be performed in case-insensitive manner. It is significantly slower than the default case-sensitive algorithm. RESULT Tracker - hashed tree tracker. The tree is referenced always by this tracker. SEE ALSO AddHashItem, FindHashItem, FreeObject ss.library/IPAlloc ss.library/IPAlloc NAME IPAlloc -- Allocate memory in internal pool SYNOPSIS Block = IPAlloc(Size); D0 D0 FUNCTION Allocates memory in task's private pool. This private pool is created automatically during StartupInit and freed during ExitCleanup. This pool is automatically used for storage of trackers and similar small objects. The primary use of this function is allocation of few small blocks of memory when creation of custom memory pool causes unwanted extra overhead. INPUTS Size - requested size RESULT Block - Pointer to allocated memory block. NOTE The block allocated by this function is guaranteed to be cleared. If there's not enough memory, the program is exited immediately. SEE ALSO PoolAlloc, StartupInit, ExitCleanup ss.library/IPFree ss.library/IPFree NAME IPFree -- Free memory in internal pool. SYNOPSIS IPFree(Chunk, Size); A1 D0 FUNCTION Frees memory allocated by IPAlloc. Partial freeing is not allowed. INPUTS Chunk - address of memory chunk you want to free. Size - size of the chunk. SEE ALSO TrackPool, PoolAlloc ss.library/LinearAlloc ss.library/LinearAlloc NAME LinearAlloc -- Allocate word-aligned space in linear pool. SYNOPSIS Mem = LinearAlloc(Pool, Size); D0 A0 D1 FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (always even) or NULL if no memory available and err_memory disabled. NOTE If you don't depend on evenness of the allocated block, use LinearAllocN instead. FUNCTION Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (always even) or NULL if no memory available and err_memory disabled. WARNING The Size parameter is given in D1 and NOT in D0 as usually the first non-address parameter is. SEE ALSO TrackLinPool, LinearAllocN ss.library/LinearAllocN ss.library/LinearAllocN NAME LinearAllocN -- Allocate unaligned space in linear pool. SYNOPSIS Mem = LinearAllocN(Pool, Size); D0 A0 D1 FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). Doesn't word-align the allocation, therefore is usually used for allocation of strings. Slightly faster than LinearAlloc. If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (may be odd) or NULL if no memory available and err_memory disabled. WARNING The Size parameter is given in D1 and NOT in D0 as usually the first non-address parameter is. SEE ALSO TrackLinPool, LinearAlloc ss.library/LoadFile ss.library/LoadFile NAME LoadFile -- Load whole file to memory. SYNOPSIS File, Tracker = LoadFile(FileName); D0 D1 A0 FUNCTION Read file from disk to memory. Uses TrackOpen, TrackMem and ChkRead and reports their errors if enabled. This function is able to decrunch powerpacked files using the powerpacker library. Encrypted files are not supported yet. Also files packed by the XPK library are automatically decrunched if the library is available. Error processing mechanism depends on err_openread and err_read error bits. INPUTS FileName - pointer to name of file you want to read. RESULT File - Pointer to file in memory. The file is preceeded by one longword containing file size in bytes and is always null-terminated (useful mostly for text files). Zero when unsuccessful and the default error processing is disabled. Tracker (D1) - Tracker of memory area containing the file or NULL if unsuccessful. NOTE The memory block the file is stored to is allocated via TrackAllocPub, therefore it's possible to specify your own memory requirements in sv_memattr (default MEMF_PUBLIC). BUGS Reading from interactive filehandles is not implemented, because it is not possible to estimate size of interactive file. If requested, appropriate error message is displayed. SEE ALSO ChkRead, TrackOpen, TrackAlloc, FreeObject ss.library/MergeResLists ss.library/MergeResLists NAME MergeResLists -- Merge two resource lists to one. SYNOPSIS MergeResLists(); FUNCTION Merges current resource list with the previous one. Returns without doing any action if less than two resource lists are defined. Used when you want to track some objects and connect them to the main resource list, but if some allocation fails, all the allocated objects have to be freed without freeing of the main resource list: CreateResList(); -- do the allocations here -- if (Failed) FreeResList(); else MergeResLists(); In many cases, it's better to use CallBlock which does many things automatically. SEE ALSO CreateResList, FreeResList, CallBlock ss.library/ParseArgs ss.library/ParseArgs NAME ParseArgs -- Parse CLI Argument String. SYNOPSIS Success, Tracker = ParseArgs(Source, Template, ExtraHelp, D0 D1 A0 A1 A2 Destination, Flags); A3 D0 FUNCTION Parse arguments. This function does something similar to dos/ReadArgs, but there are some little enhancements: - Automatic processing of errors (the program is automatically halted after error if it isn't disabled by the corresponding flag bit). - Ability to process non-decimal numbers in /N arguments (see StrToL). - Tracking functions are used for allocation of additional memory. - Provides mechanism for processing of default settings of non-/A arguments. - Arguments specified in default settings may be overriden or disabled by placing the minus ("-") sign before their keywords. For example: Let's have the template "NAME/K,SWITCH/S,ANOTHER/S" Default is "NAME Something ANOTHER" Parameters are "NAME Suspicious -ANOTHER SWITCH" Result is: NAME="Suspicious", ANOTHER=FALSE, SWITCH=TRUE The typical example of using ParseArgs with defaults is: if (! ParseArgs(Defaults,Template,&Vars,pafm_nofail | pafm_ignorea)) Report_Bad_Defaults; ParseArgs(Arguments,Template,&Vars,pafm_noclear); !! The /A arguments aren't taken from the defaults. INPUTS Source - string to be parsed. NULL means that the string has too be fetched from the standard buffered input (this is where the default arguments are stored by the shell). Template - template describing the arguments. ExtraHelp - an extra help string to be displayed when the user enters '?' the second time. Destination - the array you want to store the arguments to. Flags - some flags controlling the parsing (see below). RESULT Success - boolean value indicating success (always true when the automatic error processing is turned on). Tracker (D1) - object tracker of buffers associated with the result of the parsing. FLAGS pafb_nofail - disable automatic processing of errors pafb_noclear - don't clear the array before parsing pafb_ignorea - don't check presence of /A arguments NOTE You can freely modify the arguments returned by this function. SEE ALSO StartupInit, StrToL, dos/ReadArgs ss.library/PoolAlloc ss.library/PoolAlloc NAME PoolAlloc -- Allocate memory in private pool. SYNOPSIS Block = PoolAlloc(Pool, Size); D0 A0 D0 FUNCTION Allocates memory in given memory pool (created by TrackPool). If Size is less or equal to Threshold of memory pool, the block is allocated inside some chunk. If there is no free chunk, new one is created. Large memory blocks are allocated separately and linked to the pool. Attempt to allocate 0 bytes of memory results in alert AN_AllocZero and termination of your program. INPUTS Pool - tracker of memory pool you want to allocate the block in Size - requested size RESULT Block - Pointer to allocated memory block. SEE ALSO TrackPool, PoolFree ss.library/PoolFree ss.library/PoolFree NAME PoolFree -- Free memory in private pool. SYNOPSIS PoolFree(Pool, Chunk, Size); A0 A1 D0 FUNCTION Frees memory allocated by PoolAlloc. Partial freeing is not allowed. INPUTS Pool - address of memory pool the chunk lies in. Chunk - address of memory chunk you want to free. Size - size of the chunk. SEE ALSO TrackPool, PoolAlloc ss.library/Printf ss.library/Printf NAME Printf -- Glue to dos/VPrintf. SYNOPSIS Printf(Text, Params); A0 A1 FUNCTION The VPrintf service in the dos library has its parameters in data registers, which usually involves many instructions for reordering of the arguments. This service does this required shuffling and calls VPrintf. INPUTS Text - pointer to format string Params - pointer to parameter array SEE ALSO Puts, PutsNL, FormatString, dos/VPrintf ss.library/Puts ss.library/Puts NAME Puts -- Glue to dos/FPuts. SYNOPSIS Puts(Text); A0 FUNCTION There exists no puts() in the dos library and FPuts() has its parameters in data registers, which usually involves many instructions for reordering of the arguments. This service does this required shuffling and calls FPuts with a filehandle of your stdout. INPUTS Text - pointer to message to print out SEE ALSO PutsNL, Printf, dos/FPuts ss.library/PutsNL ss.library/PutsNL NAME PutsNL -- Glue to dos/FPuts. SYNOPSIS PutsNL(Text); A0 FUNCTION There exists no puts() in the dos library and FPuts() does not emit a newline character after the string. This function does the same action as Puts and puts an additional newline after the string. INPUTS Text - pointer to message to print out SEE ALSO Puts, Printf, dos/FPuts ss.library/QuickSort ss.library/QuickSort NAME QuickSort -- Quickly sort an array. SYNOPSIS QuickSort(Base, NumEl, ElSize, CompFunc); A0 D0 D1 A1 FUNCTION Sort array of records in ascending order. Uses a variant of the QuickSort algorithm with minimal stack requirements. Stack overflow handled and reported (err_stack). See qsort() in any C book. Uses various optimizations depending on record size. INPUTS Base - address of first element of the array NumEl - number of elements (may be zero) ElSize - size of one element (max. 65535) CompFunc - pointer to function used for comparison of two elements. Called with A0=&El1, A1=&El2. Returns -1 if El1 < El2, 1 if El1 > El2, 0 if El1 == El2. May modify D1, A0 and A1. A5 passed without changes. SEE ALSO SortLongs, SortStrings, SortList, SortListName ss.library/RelinkObject ss.library/RelinkObject NAME RelinkObject -- Relink object to main resource list. SYNOPSIS RelinkObject(Object); A0 FUNCTION Relink tracked object to the first resource list. You are not allowed to relink master/slave object. This will be fixed in some future version. INPUTS Object - object to be relinked SEE ALSO TrackObject, CreateResList, FreeResList, FreeObject ss.library/RemExtension ss.library/RemExtension NAME RemExtension -- Remove last extension from file name. SYNOPSIS RemExtension(Name); A0 FUNCTION Remove filename extension if there's any. INPUTS Name - pointer to file name to remove extension of SEE ALSO AddExtension, SetExtension, GetExtension ss.library/ReportError ss.library/ReportError NAME ReportError -- Handle an error condition. SYNOPSIS ReportError(ErrorCode, Arg1, Arg2, Arg3); D0 A1 D2 D3 FUNCTION If the error bit corresponding to given error code is clear, error message is displayed and the program is stopped via ExitError(). If the error bit is set, nothing happens and ReportError() returns with zero in both D0 and D1. INPUTS ErrorCode - code of error which has happened (see ss.i) Arg1 - first argument to be substituted to error message Arg2 - second argument Arg3 - third argument SEE ALSO ExitError, DisplayError, DosError ss.library/SetExtension ss.library/SetExtension NAME SetExtension -- Set last extension in file name. SYNOPSIS Success = SetExtension(Name, Buffer, Extension, BufSize); D0 A0 A1 A2 D0 FUNCTION Set last extension of given file name or add it if there's no extension yet. INPUTS Name - name to set extension in Buffer - buffer to store the result to Extension - extension to be used BufSize - size of the buffer RESULT Success - TRUE if successful, FALSE if buffer overflow. SEE ALSO AddExtension, GetExtension, RemExtension ss.library/SimpleRequest ss.library/SimpleRequest NAME SimpleRequest -- Simple stub for EasyRequest. SYNOPSIS num = SimpleRequest(Text, Params, Gadgets); D0 A0 A1 A2 FUNCTION Display a message using intuition/EasyRequest, but with significantly simpler arguments. For additional information see EasyRequest. INPUTS Text - pointer to message you want to display Params - pointer to optional parameters for printf-style formatting Gadgets - pointer to string containing texts for requester gadgets separated by '|' RESULT num - See EasyRequest SEE ALSO DisplayError, intuition/EasyRequest ss.library/SortList ss.library/SortList NAME SortList -- Sort linked list. SYNOPSIS SortList(List, Func); A0 A1 FUNCTION Sort standard double-linked list using user-supplied node comparison function. INPUTS List - pointer to list header Func - pointer to function used for comparision of two list nodes. A0=&&Node1, A1=&&Node2. Returns -1 if Node1 < Node2, 1 if Node1 > Node2 and 0 if Node1 == Node2. A5 is passed without changes. WARNING This function allocates a block of memory and _requires_ the err_memory bit set. SEE ALSO QuickSort, SortListName ss.library/SortListName ss.library/SortListName NAME SortListName -- Sort linked list by node name. SYNOPSIS SortListName(List); A0 FUNCTION Sort standard double-linked list by LN_NAME. (uses utility/Stricmp for comparison of node names) INPUTS List - pointer to list header WARNING This function allocates a block of memory and _requires_ the err_memory bit set. ss.library/SortLongs ss.library/SortLongs NAME SortLongs -- Sort an array of unsigned longwords. SYNOPSIS SortLongs(Array, NumEl); A0 D0 FUNCTION Sort an array of unsigned longword integers in ascending order. INPUTS Array - pointer to array you want to sort NumEl - number of elements SEE ALSO QuickSort, SortStrings ss.library/SortStrings ss.library/SortStrings NAME SortStrings -- Sort an array of string pointers. SYNOPSIS SortStrings(Array, NumEl); A0 D0 FUNCTION Sort an array of string pointers in ascending order of strings. Uses utility/Stricmp to compare the strings. INPUTS Array - pointer to array you want to sort NumEl - number of elements SEE ALSO QuickSort, SortLongs ss.library/StartupInit ss.library/StartupInit NAME StartupInit -- Standard startup procedure of program. SYNOPSIS StartupInit(StartupStruct, WbMsg); A0 D7 FUNCTION Performs standard startup initialization which includes: - Checks ss.library version requested by your program. - Allocate space for system variables and your own variables. The A5 register points to this memory region (directly to the ssbase item) allowing simple determination of the library base using MOVE.L (A5),A6. The system variables are stored below A5 (as described in SS.i) and may grow in future releases. Your own variables are stored above A5. The amount of user's variables is stored in the StartupStruct (as described below). - All system variables are initialized to their proper values. - All of your own variables are initialized to zeroes. - Automatically opens some libraries (dos, intuition, gfx, gadtools, utility) - Program name is determined and stored to system variable. - Current task is added to the CallerList, which allows to recover from a soft crash (see ExitCleanup for further explaination). - All actions requested by the tags are done (see below). - The arguments are parsed in both CLI and WB modes. If the WB has called us, the tool types are parsed using supplied template and converted to CLI arguments. If there's a multi-selected icon, it will be used as the first argument (if the first argument is /M, all multiselected icons will be parsed). If the program has been called as a default tool of some project, the project's name is used as the 1st argument. If there is some icon used as the first argument, its tool types override the program's ones. - If the program is started from Workbench, its current directory is set to its home directory or to directory containing the first argument. - Task's exception handler is replaced by custom one. It shows all address and data registers, the program counter and the status register (SR). The user may suspend the program, try to abort it (in this case, all resources tracked by SS functions are freed) or reboot the machine. [The exception code is NOT replaced if there is already another exception handler stored in RAM -> you can use breakpoints in your favourite debugger etc.] [The algorithm used for detection of custom exception handler might have some problems with future kickstarts larger than 1/2 Meg.] - Address of the ExitCleanup function is pushed onto stack allowing simple exit by usual RTS instruction. The tags parsed by this function are stored in a special (read: non-standard) format. This format uses variable-length tagitems: a) Special SSLib trackers (codes 0000-3FFF). These trackers have absolutely non-systematic arguments, therefore if SSLib encounters any unknown tag of this type (e.g., generated by newer version of the macros), it can't be simply ignored => the "Unknown Tracker" alert is shown and the program is terminated. If you use these trackers, make sure that your "required version number" value matches all these tag types you're using. This is usually done automatically by ssmac.h. b) Longword trackers. These are utility.library compatible with one small exception: TAG_IGNORE, TAG_MORE and TAG_SKIP are not supported and they act as TAG_END. The implementation is very simple: TAG_END ($00000000) is understood as a special SSLib tracker $0000 with the same meaning. All other longword trackers start with $8000, which says that StartupInit has to fetch next word as tag ID and next longword as tag parameters (in case of string args, it's a pointer to the string). The tag ID must be in range 8000-FFFF. c) Optional trackers (C000-FFFF). These trackers have variable size of argument, but there's a simple mechanism to determine this size: it's encoded in bits #12 and #13 of tag ID: 00 means no parameters, 01=one word, 10=one longword, 11=string (null-terminated and padded by zeroes to even length). If one of these optional trackers is encountered and cannot be interpreted, it's simply skipped. d) Extended trackers (4000-7FFF). Similar to Optional trackers, but can't be ignored. Many pointers in the tags are relative (marked as RelPtr). They can be simply generated by the following macro: RelPtr macro \@a dc.w \1-\@a endm INPUTS StartupStruct - pointer to startup structure (see StartupStruct in ss.i). It consists of two words followed by the tags. The first word contains requested size of user's variables and must be at least 4 (the first variable is always a pointer to base of ss.library). The second one specifies which version of ss.library does the program require. WbMsg - pointer to WorkBench startup message (you must get it manually). Can be any value when started from CLI. Must be 0 when started from process created by CreateProc, which is NOT started by the WorkBench. This sounds very complicated - see the start macro in ssmac.h if you are confused. RESULT A5 points to the variable zone. This value is required by all services of this library excluding where this doc says something other. If you call SSLib with different value in A5, weird things can occur (and really occur). TAGS sst_finish - End of TagList. sst_wbconsole - Create console window if started from WB. This window is used as standard input and output. sst_template (string,word) - Specifies argument template and offset from A5 to store the arguments on (see ParseArgs). sst_usertrk (RelPtr) - Defines user tracker types. You pass a relative tointer to UserTrkTypes structure: DC.B NumberOfTrackers,0 followed by RelPtrs to freeing routines (see FreeObject). sst_extrahelp (string) - Defines extra help string for argument parsing. sst_exitrout (RelPtr) - Define exit routine, which will be called by ExitCleanup (or any error exit routine) before any cleanup is done. This mechanism can be used for closing of windows and other similar actions. The exit routine may call ExitCleanup and the error exit routines, in which case it won't be called again and may modify all registers except A5. In case of fail during StartupInit, this routine is not called. sst_usererr (RelPtr) - Defines user's error routine. This routine will be called by DisplayError and all error routines which display errors. The routine will have the same parameters as DisplayError (A0=Message, A1=FormatData). If this routine calls any of the error functions, it will be called again. sst_nowbstart - Exit with error message when called from WB. sst_library (string,WV,W) - Open library of specified name and version (WV), store its base to variable specified by its offset from A5 (W). Exit with error message if can't be opened. sst_trylib (string,WV,W) - Try to open library (same function as previous tag, but if fails, the program will continue with base=0). sst_nowbargs - Don't parse WB arguments. sst_noprogname - Don't print program's name in error messages. sst_cputype (Min,Max) - Fail if CPU type isn't in specified range. 0=68000...4=68040, -1=no upper limit sst_fputype (Min,-1) - Fail if FPU type isn't in specified range. 0=none,1=68881,2=68882,3=68040 sst_sysver (Min,Max) - Fail if kickstart version isn't in specified range. sst_errorreq - Forces using of requesters for error messages. sst_errors (BitMap.L) - Disable automatic processing of specified errors (see SS.i for constants (err_xxx)). sst_wbconname (string) - Use WB Console specified by name sst_envvar (string) - Try to fetch default values of parameters from given environment variable. These parameters are overriden by values entered by the user. sst_poolsize (PoolSize.L) - Specify size of task's private memory pool. This pool is used for allocation of all trackers. Default size = 512 bytes. Specify higher values when using tracking very frequently. This tag MUST be specified before all other tags. The value must be an integer multiple of 8. sst_poolthresh (PoolThr.L) - Specify threshold of task's private memory pool (see TrackPool, PoolAlloc). Default threshold=373. Usage: rare. This tag MUST be specified directly after sst_poolsize or at the start if there is no poolsize tag. sst_nostderr - Force stderr=stdout. Don't open "*" for stderr. sst_noiconarg - don't pass names of multiselected icons as the first argument. They will be simply ignored. sst_nocliargs - pass CLI argument line directly to your program without preprocessing of any kind. If this tag is not specified and no template is given, all input arguments are discarded to prevent usual strange behaviour of standard buffered input. WARNING All registers excluding A4 and A6 are modified by this call. BUGS Argument parsing could be problematic when running from several debuggers (for example MonAm older than 3.04), because SSLib uses standard V37 way to pass them using buffered standard input. See also ssmac.h for some workaround. Also stderr may be incorrect in this case. But this is NOT a bug in ss.library, it is a result of bugs in the debuggers. SEE ALSO ExitCleanup, ExitError ss.library/StrCat ss.library/StrCat NAME StrCat -- Concatenate two strings. SYNOPSIS StrCat(Destination, Source); A0 A1 FUNCTION This function performs usual string concatenation. INPUTS Destination - destination string Source - source string RESULT A0 contains address of the null character at the end of the destination string. It allows to concatenate multiple strings without reloading of the destination pointer. ss.library/StrToL ss.library/StrToL NAME StrToL -- Convert string to long integer number. SYNOPSIS Value, Position = StrToL(String); D0 D1 A0 FUNCTION Convert string containing a number in ASCII form to binary form. It supports decimal, octal (prefixed by 0) and hexadecimal (prefixed by 0x or $) numbers. All spaces before the number are skipped. If there're any invalid characters, the standard error mechanism is used. If the user hadn't disabled it, the error message err_number is displayed and the program is terminated. INPUTS String - string to be converted RESULT Value - Value of number or 0 if invalid. Position (D1) - address of first invalid character if failed or zero if the input string contains valid number. ss.library/TestBreak ss.library/TestBreak NAME TestBreak -- Test if the user has pressed break. SYNOPSIS TestBreak(); FUNCTION Tests the CTRL-C signal and aborts the program if detected. If the err_break bit is not set, this function only resets the break signal. NOTE Doesn't modify contents of D0,D1,A0,A1. Library base not needed in A6. SEE ALSO exec/SetSignal, arp/CheckAbort, arp/CheckBreak, dos.i ss.library/TestStack ss.library/TestStack NAME TestStack -- Check stack overflow. SYNOPSIS TestStack(); FUNCTION Test stack overflow and abort the program if it occured. The lowest possible value of SP is taken from sv_stklimit, which is initially set (by StartupInit) to TC_SPLOWER+128. NOTE Doesn't modify contents of D0,D1,A0,A1. Library base not needed in A6. The stack overflow error cannot be disabled. SEE ALSO TestBreak, StartupInit, ReportError ss.library/TrackAlloc ss.library/TrackAlloc NAME TrackAlloc -- Allocate cleared memory and track it. SYNOPSIS MemBlock, Tracker = TrackAlloc(Size); D0 D1 D0 FUNCTION Allocate, clear and track public memory of specified size. If the memory is not available, exit with error message if its's enabled by the corresponding error bit. If you want to allocate large block of memory and you don't need it to be cleared, use TrackAllocPub(Size) instead. INPUTS Size - how large (in bytes) chunk of memory you want to allocate. RESULT MemBlock - pointer to allocated and cleared memory block or 0 if not enough memory and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAllocMem, TrackAllocPub, FreeObject, exec/AllocMem ss.library/TrackAllocMem ss.library/TrackAllocMem NAME TrackAllocMem -- Allocate memory and track it. SYNOPSIS MemBlock, Tracker = TrackAllocMem(Size, Requirements); D0 D1 D0 D1 FUNCTION Allocate and track memory of specified size with specified attributes. If the memory is not available, exit with error message if its's enabled by the corresponding error bit. INPUTS Size - how large (in bytes) chunk of memory you want to allocate. Requirements - memory requirements (as for AllocMem) RESULT MemBlock - pointer to allocated memory block 0 if not enough memory of required type and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAlloc, TrackAllocPub, FreeObject, exec/AllocMem ss.library/TrackAllocPub ss.library/TrackAllocPub NAME TrackAllocPub -- Allocate public memory and track it. SYNOPSIS MemBlock, Tracker = TrackAllocPub(Size); D0 D1 D0 FUNCTION { no, this doesn't allocate a free place in a pub } Allocate region of public memory. Doesn't perform any clearing! The exact memory attributes used are determined by the sv_memattr variable. TrackAllocPub is an equivalent to TrackAllocMem (Size,sv_memattr). This mechanism allows some standard functions which allocate public memory (LoadFile, TrackBufHandle etc) to use your own memory attributes instead of usual MEMF_PUBLIC. INPUTS Size - how large (in bytes) chunk of memory you want to allocate. RESULT MemBlock - pointer to allocated memory block or 0 if not enough memory and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAllocMem, LoadFile, TrackBufHandle ss.library/TrackBufHandle ss.library/TrackBufHandle NAME TrackBufHandle -- Allocate and track handle for buffered I/O SYNOPSIS Handle = TrackBufHandle(Filename, OpenMode, BufSize); D0 A0 D0 D1 FUNCTION Allocates a handle for buffered I/O and the I/O buffer associated with it. The handle is initialized in the following way: - bh_handle = -1 (if it was 0, the tracker freeing routine wouldn't be called). - bh_name = the Filename parameter. - bh_readfunc, bh_writefunc and bh_seekfunc point to simple routine displaying alert AN_IONotSupported which is shown if someone doesn't initialize the routine pointers properly and tries to do I/O with them. - bh_bufsize = size of the buffer - bh_buffer = start of the buffer - bh_dataend = bh_buffer - bh_bufend = bh_buffer + bh_bufsize - bh_current = bh_buffer - bh_eofhook = pointer to RTS instruction (empty EOF hook) - bh_flags = flags set according to OpenMode (see ss.i) - bh_arg1 = bh_arg2 = 0 If you want to do buffered I/O with this handle, set: - bh_handle = whatever you want (can be used by your block I/O subroutines) - bh_read = pointer to block read routine (only for read streams). The routine is called with A0 pointing to the handle, A1 saying where to load the block to, D0 containing the block length. It should return D0=number of bytes read. - bh_write = pointer to block write routine (only for write streams). Called with parameters identical to those in bh_read, but doesn't return anything. - bh_seek = pointer to seek routine. Called with A0=handle, D0=offset to seek to (absolute). Result: none. - These block I/O routines are guaranteed to receive A4 and A5 from caller program. In case of I/O error, they mustn't return (ExitError or something similar has to be called). - bh_arg1, bh_arg2 - set to anything you want (for use by your I/O routines) - bh_eofhook - set to your EOF hook if you need. This hook will be called as soon as EOF will be encountered after reading of block by bh_readfunc. To force normal EOF operation, the hook should return normally without changing ANY registers. In other cases, it should call ExitError("Unexpected EOF") or something similar. If you want to associate the tracker of your I/O object with this handle tracker via the TrackSlave mechanism, you shouldn't use this one as a master, because trk_ext contains bh_name. INPUTS Filename - file name to be used in error reports. OpenMode - OPEN_OLD for read access, OPEN_NEW or OPEN_APPEND for write access. OPEN_LINEBUF may be added (not ORed!) to obtain line buffering (buffers are flushed whenever the end of line character is written). BufSize - buffer size to be used. May be zero to specify default buffer size (now 4K, may change in future versions). Must be larger than 16 bytes and dividable by 4. RESULT Handle - buffered I/O handle (tracker). NOTE The functions for doing buffered I/O have slightly non-standard arguments - stream handle is passed in A2 for read streams and in A3 for write streams. If it's possible to use the function for both read and write streams, it comes in A2. This strange behavior has been chosen to allow calling of long sequences of I/O calls without reloading the stream pointer. The stream tracker should be used the task which created it, because various things depend on caller's A5. The buffer itself is allocated via TrackAllocPub, therefore it's possible to specify your own memory requirements via sv_memattr (default is MEMF_PUBLIC). SEE ALSO TrackOpenBuf, B*, FreeObject ss.library/TrackDevice ss.library/TrackDevice NAME TrackDevice -- Open device and track it. SYNOPSIS Error, Tracker, IORQ = TrackDevice(DevName, IORQ, Unit, Flags, D0 D1 A1 A0 A1 D0 D1 ErrTable); A2 FUNCTION Open device and track it. In case of difficulty, write an error message and abort the program if requested by corresponding error bit. INPUTS DevName - device name, case-sensitive IORQ - IORequest to use with this device (if IORQ<256, TrackIoRq(0,IORQ) will be called to create new IORequest, which will be linked by TrackSlave to device's tracker). Unit - device unit number Flags - OpenDevice flags ErrTable - optional pointer to error message table (this pointer MUST be specified if you want to use ChkDoIO, but it may be NULL). The table is a sequence of error definition blocks terminated by a block of 0 errors (both Min and NumErr fields are zero). Each block starts with two words of data: the first one contains number of first error message in the block, the second one contains number error messages. The header is followed by an array of longwords pointing to names of errors. RESULT Error - Error code or 0 if successful. Tracker (D1) - object tracker. trk_data contains pointer to associated IoRequest structure, trk_sizeof[0] points to the error table (as given in A2). IORQ (A1) - copy of trk_data (pointer to associated IORequest) SEE ALSO ChkDoIO, TrackIORQ, TrackPort, FreeObject, exec/OpenDevice ss.library/TrackDosObject ss.library/TrackDosObject NAME TrackDosObject -- Allocate a dos object and track it. SYNOPSIS DosObject, Tracker = TrackDosObject(Type, TagList); D0 D1 D0 A0 FUNCTION Allocate dos object and track it. Does usual error handling and reporting (err_memory). INPUTS Type - dos object type TagList - dos object tag list RESULT DosObject - pointer to allocated dos object or 0 if not successful. Tracker (D1) - object tracker. trk_data points to the object, trk_ext contains object type. SEE ALSO dos/AllocDosObject, FreeObject ss.library/TrackExtd ss.library/TrackExtd NAME TrackExtd -- Create an extended tracker. SYNOPSIS Tracker, Tracker, TrkExt = TrackExtd(Type, ExtSize); D0 A0 A1 D0:8 D1 FUNCTION Create an extended tracker structure and connect it to active resource list (if there's no resource list, one will be created). The extended tracker is a standard resource tracker, which has some additional data behind trk_sizeof. These bytes are for your own use. INPUTS Type - tracker type (see ss.i) ExtSize - size of tracker extension block RESULT Tracker - pointer to newly created object tracker Tracker (A0) - pointer to the tracker TrkExt (A1) - pointer to trk_ext field of the tracker SEE ALSO TrackObject, FreeObject ss.library/TrackIoRq ss.library/TrackIoRq NAME TrackIoRq -- Create an IoRequest and track it. SYNOPSIS IORQ, Tracker = TrackIoRq(OptionalPort, Size); D0 D1 A0 D0 FUNCTION Create an IO Request and track it. This function can use user-supplied message port or create special message port for this IORQ. In case of difficulty, writes error message and aborts the program if requested by corresponding error bit. INPUTS OptionalPort - pointer to message port to be used as a reply port for the IoRequest. If NULL, new port will be created including new signal. Size - size of the IoRequest or 0 for size of the IoExtStd structure. RESULT IORQ - pointer to newly created IoRequest structure. Tracker (D1) - obejct tracker. trk_data points to the IoRequest SEE ALSO TrackPort, TrackDevice, FreeObject ss.library/TrackLibrary ss.library/TrackLibrary NAME TrackLibrary -- Open a library and track it. SYNOPSIS Library, Tracker = TrackLibrary(LibName, Version); D0 D1 A0 D0 FUNCTION Open library and track it. If the library isn't available and you hadn't disabled it by the error bits, an error message will be displayed and the program will be aborted. INPUTS LibName - name of library, case is significant. Version - required minimal version (0=any). RESULT Library - pointer to library node or 0 if unsuccessful. Tracker (D1) - object tracker. trk_data contains pointer to base of the library (as returned in D0). SEE ALSO FreeObject, StartupInit, exec/OpenLibrary ss.library/TrackLinPool ss.library/TrackLinPool NAME TrackLinPool -- Create a linear memory pool and track it. SYNOPSIS LinPool = TrackLinPool(Quantum, Attributes); D0 D0 D1 FUNCTION Create a linear memory pool and track it. Linear pooled allocation is an extremely fast memory allocation strategy designed for allocating of small blocks of memory, which are freed together. The pool manager allocates memory in large blocks of given size (Quantum). It tries to use currently active block for each allocation request. If it fails, new block is created. INPUTS Quantum - allocation quantum Attributes - requested memory attributes (see AllocMem) RESULT LinPool - Pointer to linear memory pool tracker. SEE ALSO FreeObject, LinearAlloc, LinearAllocN ss.library/TrackLock ss.library/TrackLock NAME TrackLock -- Lock dos object and track it. SYNOPSIS Lock, Tracker = TrackLock(Name, LockMode); D0 D1 A0 D0 FUNCTION Lock dos object and track it. Error handling as usually. INPUTS Name - name of the object you want to lock. This pointer is stored in the tracker to be used later for reporting of errors, therefore you are not allowed to modify the name before freeing of the tracker. LockMode - lock mode (see dos.i) RESULT Lock - Dos lock or 0 if failed. Tracker (D1) - object tracker. trk_data contains the lock, trk_ext points to the name. SEE ALSO dos/Lock, FreeObject ss.library/TrackObject ss.library/TrackObject NAME TrackObject -- Create a standard tracker. SYNOPSIS Tracker, Tracker, TrkExt = TrackObject(Type); D0 A0 A1 D0:8 FUNCTION Create a standard tracker and connect it to active resource list (if there's no resource list, new one will be created). This function is used to track objects of your own types defined using the UserTrkTypes structure (tracker types in range $80 to $FF) or to track objects defined by ss.library extensions (not implemented yet). Your object freeing function will be called ONLY if the trk_data field contains non-null value. This suspiciously-looking rule allows you to track your objects simply with respect to all possible failures: - call TrackObject (if there isn't enough memory to do it -> aborted) - store A1 - allocate your object - restore A1 - store optional data at A1 if you need - store pointer to your object to -(A1) If allocation of your object fails and you abort the program, you don't have to free the tracker, because it will be done automatically by ExitCleanup (or other exit routine, which calls ExitCleanup) and your object-freeing routine won't be called. If you don't abort the program, you have simply to free the tracker using FreeObject and your object-freeing routine won't be called, too. INPUTS Type - tracker type (as described in ss.i) RESULT Tracker - pointer to newly created object tracker Tracker (A0) - pointer to the tracker TrkExt (A1) - pointer to trk_ext field of the tracker NOTE There are some cases in which you want to suppress freeing of already tracked object (for example if you write some patch utility leaving patch code in memory after successful exit, but freeing it in case of failure). It can be solved very simply by calling Remove(Tracker) - the tracker will be removed cleanly. If you use this method, ExitCleanup will destroy the trackers themself (they are stored in a memory pool which is private to each task and is freed during the cleanup), but the tracked objects are not affected. Do not call FreeObject on disconnected objects. Another way to do such a thing is to set Tracker.trk_type to trt_null, but it makes using of additional FreeObject() impossible, because it will free only the tracker, not the tracked object. You are not allowed to manipulate the positions of objects in the lists. If you really need to do such a thing, use RelinkObject(). SEE ALSO CreateResList, FreeObject, FreeResList, GetResList, TrackRoutine, TrackExtd, RelinkObject ss.library/TrackOpen ss.library/TrackOpen NAME TrackOpen -- Open a file and track it SYNOPSIS FH, Tracker = TrackOpen(Name, OpenMode); D0 D1 A0 D0 FUNCTION Open a file and track it. Does usual error checking and handling (see some other tracking function). INPUTS Name - name of the file you want to open. This pointer is stored in the tracker to be used later in error reports, therefore you are not allowed to modify the name until you free the tracker. OpenMode - Open() mode - see dos/dos.i - MODE_*. You can also use one of SS open modes: OPEN_OLD (a synonym to MODE_OLDFILE, but slightly shorter value movable by MOVEQ), OPEN_NEW (identical to MODE_NEWFILE) or OPEN_APPEND (uses MODE_READWRITE and Seek() to EOF). RESULT FH - File handle or 0 if failed. Tracker (D1) - object tracker. trk_data contains file handle, trk_ext points to file name. SEE ALSO dos/Open, dos.i, FreeObject ss.library/TrackOpenBuf ss.library/TrackOpenBuf NAME TrackOpenBuf -- Open file for buffered I/O SYNOPSIS Handle = TrackOpenBuf(Filename, OpenMode, BufSize); D0 A0 D0 D1 FUNCTION Obtains a buffered I/O handle via TrackBufHandle, opens a DOS file of given name and associates it with the handle. INPUTS Filename - name of the file you wish to open OpenMode - OPEN_OLD for read access, OPEN_NEW for write access to new file, OPEN_APPEND for appending to possibly existing file (if doesn't exist, it's created immediately). OPEN_LINEBUF may be added (not ORed!) to request line buffering for interactive files (buffers are flushed whenever the end of line character is written). If the file is not interactive, this flag is automatically reset. If you want to do line-buffered I/O with non-interactive files, you should set the biob_linebuf bit in bh_flags after calling this function. BufSize - buffer size to be used. May be zero to specify default buffer size (now 4K, may change in future versions). Must be larger than 16 bytes and dividable by 4. RESULT Handle - buffered I/O handle (tracker). May be used as a file tracker for ChkRead and similar functions. NULL if opening failed and err_open is not set. NOTE If you want to do anything with the file handle returned in bh_handle, remember to call BFlush before and don't forget to update bh_position to reflect the changes you have made. When doing I/O, TestBreak is sometimes called automatically. The only fields in the handle you are allowed to modify are: bh_eofhook and bh_flags (but only the biob_linebuf bit in it) plus some other fields as shown in recommended inline versions of some I/O functions. WARNING The file I/O error bits (err_read, err_write and err_seek) _must_ be set for buffered I/O. If it's needed to do some special error handling, call the whole sequence of I/O subroutines by CallBlock and test the errors by this way. SEE ALSO TrackBufHandle, B*, TrackOpen, FreeObject ss.library/TrackOpenBufFH ss.library/TrackOpenBufFH NAME TrackOpenBufFH -- Open a buffered I/O stream from given file handle SYNOPSIS Handle = TrackOpenBufFH(Filename, OpenMode, BufSize, FileHandle); D0 A0 D0 D1 D2 FUNCTION Obtains a buffered I/O handle via TrackBufHandle and associates an already opened DOS file handle to it. For more information, see TrackOpenBuf. INPUTS Filename - file name used for error reports OpenMode - OPEN_OLD for read access, OPEN_NEW for write access to new file, OPEN_APPEND for appending at the end. OPEN_LINEBUF may be added (not ORed!) to request line buffering for interactive files (buffers are flushed whenever the end of line character is written). If the file is not interactive, this flag is automatically reset. If you want to do line-buffered I/O with non-interactive files, you should set the biob_linebuf bit in bh_flags after calling this function. BufSize - buffer size to be used. May be zero to specify default buffer size (now 4K, may change in future versions). Must be larger than 16 bytes and dividable by 4. FileHandle - file handle to be used (will be stored in bh_handle). RESULT Handle - buffered I/O handle (tracker). May be used as a file tracker for ChkRead and similar functions. NULL if opening failed and err_open is not set. NOTE If you want to do anything with the file handle you have supplied, remember to call BFlush before and don't forget to update bh_position to reflect the changes you have made. When doing I/O, TestBreak is sometimes called automatically. The only fields in the handle you are allowed to modify are: bh_eofhook and bh_flags (but only the biob_linebuf bit in it) plus some other fields as shown in recommended inline versions of some I/O functions. SEE ALSO TrackOpenBuf, TrackBufHandle, FreeObject ss.library/TrackPool ss.library/TrackPool NAME TrackPool -- Create private memory pool and track it. SYNOPSIS MemPool = TrackPool(Quantum, Threshold, Attributes); D0 D0 D1 D2 FUNCTION Create a memory pool and track it. Error checking is performed according to common rules (see elsewhere what does it mean). Pooled allocation is a relatively fast memory allocation strategy designed for manipulating small blocks of memory. It's based on memory chunks, each of them has given size (Quantum). Any memory block requested by PoolAlloc, which size is less or equal to Threshold, is allocated inside one of memory chunks. Blocks greater than Threshold are allocated using standard AllocMem and linked to the pool. All memory blocks in the pool can be freed separately or simultaneously by FreeObject. INPUTS Quantum - allocation quantum Threshold - size of largest block allocated inside chunks Attributes - requested memory attributes (MEMF_#? - see AllocMem) RESULT MemPool - pointer to memory pool tracker SEE ALSO FreeObject, PoolAlloc, PoolFree, exec/AllocMem ss.library/TrackPort ss.library/TrackPort NAME TrackPort -- Create a message port and track it. SYNOPSIS Port, Tracker = TrackPort(); D0 D1 FUNCTION Create a message port and track it. Does usual error checking and handling. RESULT Port - pointer to newly created MsgPort structure. Tracker (D1) - object tracker. trk_data points to the port. SEE ALSO exec/CreateMsgPort, FreeObject, TrackIORQ ss.library/TrackRoutine ss.library/TrackRoutine NAME TrackRoutine -- Create tracker with custom freeing routine. SYNOPSIS Tracker = TrackRoutine(Routine, Args); D0 A0 A1 FUNCTION Define a tracker, which will call your routine in time of freeing. The routine will be called with A0=Args, A2=Tracker. routine. If args=0, no routine will be called. For the reason of this suspicious action, see TrackObject (there are applied the same rules). INPUTS Routine - pointer to routine You wish to call. The routine should leave intact all registers except D0-D1/A0-A1/A6. Args - user data passed to the routine in time of resource freeing. RESULT Tracker - tracker of expected type, trk_data contains routine pointer, trk_ext=args. A1 points to Args and can be used in similar way as in TrackObject, but you should use (A1) instead of -(A1). SEE ALSO TrackObject, FreeObject ss.library/TrackSignal ss.library/TrackSignal NAME TrackSignal -- Allocate signal and track it. SYNOPSIS Signal, Tracker = TrackSignal(); D0 D1 FUNCTION Allocate a signal and track it. Does usual error checking and handling. RESULT Signal - Number of signal or -1 if there are no free signals. Tracker (D1) - object tracker. trk_data contains number of signal. SEE ALSO exec/AllocSignal, FreeObject ss.library/TrackSlave ss.library/TrackSlave NAME TrackSlave -- Join two trackers. SYNOPSIS TrackSlave(Master, Slave); A0 A1 FUNCTION Connect Slave to a list of Master's slaves and re-connect the Master to the front of current resource list, therefore it will be freed before the slaves. The linkage mechanism uses the Tracker.trk_ext field as pointer to the first slave. It causes that standard trackers (excluding trt_null) cannot be used as masters. The routine tracker (obtained via TrackRoutine) can be used, but its entry data (passed in A0 to user's resource freeing routine) will be overwritten (but it won't be 0 in any case -> the routine is called everytime). The slaves are freed in LIFO order (the last slave will be freed as first). INPUTS Master - tracker to be used as the master Slave - tracker to be used as the slave SEE ALSO TrackObject, FreeObject